---
title: CLI 명령
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

Astro에서 제공하는 명령줄 인터페이스 (CLI)를 사용하여 터미널 창에서 프로젝트를 개발, 빌드, 미리 볼 수 있습니다.

### `astro` 명령

원하는 패키지 관리자로 이 페이지에 설명된 **명령** 중 하나를 실행하고 선택적으로 **플래그**를 실행하여 CLI를 사용하세요. 플래그는 명령의 동작을 사용자 정의합니다.

가장 자주 사용하게 될 명령 중 하나는 `astro dev`입니다. 이 명령은 개발 서버를 시작하고 작업하는 동안 브라우저에서 사이트의 실시간 업데이트 미리보기를 제공합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 개발 서버를 시작합니다.
  npx astro dev
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 개발 서버를 시작합니다.
  pnpm astro dev
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 개발 서버를 시작합니다.
  yarn astro dev
  ```
  </Fragment>
</PackageManagerTabs>

터미널에 `astro --help`를 입력하면 사용 가능한 모든 명령 목록을 표시할 수 있습니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro --help
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro --help
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro --help
  ```
  </Fragment>
</PackageManagerTabs>

터미널에 다음 메시지가 표시됩니다.

```bash
astro [command] [...flags]

Commands
              add  Add an integration.
            build  Build your project and write it to disk.
            check  Check your project for errors.
       create-key  Create a cryptography key
              dev  Start the development server.
             docs  Open documentation in your web browser.
             info  List info about your current Astro setup.
          preview  Preview your build locally.
             sync  Generate TypeScript types for all Astro modules.
      preferences  Configure user preferences.
        telemetry  Configure telemetry settings.

Global Flags
  --config <path>  Specify your config file.
    --root <path>  Specify your project root folder.
     --site <url>  Specify your project site.
--base <pathname>  Specify your project base.
        --verbose  Enable verbose logging.
         --silent  Disable all logging.
        --version  Show the version number and exit.
           --help  Show this help message.
```

명령 뒤에 `--help` 플래그를 추가하면 해당 명령의 모든 플래그를 확인할 수 있습니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # `dev` 명령에 대한 모든 플래그 목록을 가져옵니다.
  npm run dev -- --help
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # `dev` 명령에 대한 모든 플래그 목록을 가져옵니다.
  pnpm dev --help
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # `dev` 명령에 대한 모든 플래그 목록을 가져옵니다.
  yarn dev --help
  ```
  </Fragment>
</PackageManagerTabs>

터미널에 다음 메시지가 표시됩니다:

```bash
astro dev [...flags]

Flags
                 --port  Specify which port to run on. Defaults to 4321.
                 --host  Listen on all addresses, including LAN and public addresses.
--host <custom-address>  Expose on a network IP address at <custom-address>
                 --open  Automatically open the app in the browser on server start
                --force  Clear the content layer cache, forcing a full rebuild.
            --help (-h)  See all available flags.
```

:::note
`npm`이 플래그를 `astro` 명령에 전달하려면 플래그 앞에 추가 `--`가 필요합니다.
:::

### `package.json` 스크립트

이러한 명령의 더 짧은 버전에 `package.json`의 스크립트를 사용할 수도 있습니다. 스크립트를 사용하면 `npm run build`와 같이 다른 프로젝트에서 익숙할 수 있는 동일한 명령을 사용할 수 있습니다.

가장 일반적인 `astro` 명령 (`astro dev`, `astro build`, `astro preview`)에 대한 다음 스크립트는 [`create astro` 마법사](/ko/install-and-setup/) 를 사용하여 프로젝트를 생성할 때 자동으로 추가됩니다.

[Astro 수동 설치](/ko/install-and-setup/#수동-설정) 지침을 따르면 이러한 스크립트를 직접 추가하라는 메시지가 표시됩니다. 자주 사용하는 명령에 대해 수동으로 이 목록에 더 많은 스크립트를 추가할 수도 있습니다.

```json title="package.json"
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}
```

플래그 없이 이러한 `astro` 명령이나 이를 실행하는 스크립트를 자주 사용하게 됩니다. 명령의 동작을 사용자 정의하려면 명령에 플래그를 추가하세요. 예를 들어, 다른 포트에서 개발 서버를 시작하거나 디버깅을 위해 자세한 로그를 사용하여 사이트를 구축할 수 있습니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # `package.json` 파일의 `dev` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
  npm run dev -- --port 8080

  # `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
  npm run build -- --verbose
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # `package.json` 파일의 `dev` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
  pnpm dev --port 8080

  # `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
  pnpm build --verbose
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # `package.json` 파일의 `dev` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
  yarn dev --port 8080

  # `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
  yarn build --verbose
  ```
  </Fragment>
</PackageManagerTabs>

## `astro dev`

Astro의 개발 서버를 실행합니다. 이는 자산을 번들링하지 않는 로컬 HTTP 서버입니다. 편집기에서 변경 사항을 저장할 때 핫 모듈 교체(HMR)를 사용하여 브라우저를 업데이트합니다.

Astro 개발 서버가 실행 중인 터미널에서 다음 단축키를 사용할 수 있습니다.

- `s + enter` 콘텐츠 레이어 데이터 (콘텐츠 및 타입)를 동기화합니다.
- `o + enter` 브라우저에서 Astro 사이트를 엽니다.
- `q + enter` 개발 서버를 종료합니다.

## `astro build`

배포용 사이트를 빌드합니다. 기본적으로 이는 정적 파일을 생성하여 `dist/` 디렉터리에 저장합니다. 모든 라우트가 [요청 시 렌더링](/ko/guides/on-demand-rendering/)되는 경우, 사이트를 제공하는 데 필요한 서버 파일이 생성됩니다.

<h3>플래그</h3>

이 명령어는 [공통 플래그](#공통-플래그)와 다음과 같은 추가 플래그를 허용합니다:

#### `--devOutput`

<p><Since v="5.0.0" /></p>

개발 기반 빌드를 출력하며 이는 `astro dev`에서 변환된 코드와 유사합니다. 이는 추가적인 디버깅 정보가 포함된 빌드 전용 문제를 테스트하는 데 유용할 수 있습니다.

## `astro preview`

`astro build`를 실행하여 생성된 정적 디렉터리 (기본적으로 `dist/`)의 콘텐츠를 제공하기 위해 로컬 서버를 시작합니다.

이 명령을 사용하면 [빌드 후](#astro-build) 로컬에서 사이트를 미리 보고 배포하기 전에 빌드 출력에서 오류를 확인할 수 있습니다. 프로덕션 환경에서 실행되도록 설계되지 않았습니다. 프로덕션 호스팅에 대한 도움이 필요하면 [Astro 웹사이트 배포](/ko/guides/deploy/) 안내서를 확인하세요.

Astro 미리보기 서버가 실행 중인 터미널에서 다음 단축키를 사용할 수 있습니다.
- `o` + `enter`: 브라우저에서 Astro 사이트를 엽니다.
- `q` + `enter`: 미리보기 서버를 종료합니다.

`astro preview` 명령은 아래에 설명된 [공통 플래그](#공통-플래그)와 결합하여 미리보기 환경을 더욱 세부적으로 제어할 수 있습니다.

## `astro check`

프로젝트에 대해 진단 (예: `.astro` 파일 내 타입 검사)을 실행하고 오류를 콘솔에 보고합니다. 오류가 발견되면 프로세스는 **1** 코드와 함께 종료됩니다.

이 명령은 CI 워크플로에서 사용하기 위한 것입니다.

<h3>플래그</h3>

명령의 동작을 사용자 정의하려면 이러한 플래그를 사용하세요.

#### `--watch`

이 명령은 프로젝트의 변경 사항을 감시하고 오류를 보고합니다.

#### `--root <path-to-dir>`

check 명령을 실행할 다른 루트 디렉터리를 지정합니다. 기본적으로 현재 작업 디렉터리를 사용합니다.

#### `--tsconfig <path-to-file>`

수동으로 사용할 `tsconfig.json` 파일을 지정합니다. 제공되지 않은 경우 Astro는 구성을 찾으려고 시도하거나 프로젝트의 구성을 자동으로 추론합니다.

#### `--minimumFailingSeverity <error|warning|hint>`

오류 코드와 함께 종료하는 데 필요한 최소 심각도를 지정합니다. 기본값은 `error`입니다.

예를 들어 `astro check --minimumFailingSeverity warning` 실행 시, 경고가 감지되면 명령이 오류와 함께 종료됩니다.

#### `--minimumSeverity <error|warning|hint>`

출력할 최소 심각도를 지정합니다. 기본값은 `hint`입니다.

예를 들어 `astro check --minimumSeverity warning`을 실행하면 오류와 경고가 표시되지만 힌트는 표시되지 않습니다.

#### `--preserveWatchOutput`

감시 모드에서 check 사이의 출력을 지우지 않도록 지정합니다.

#### `--noSync`

프로젝트를 검사하기 전에 `astro sync`를 실행하지 않도록 지정합니다.

<ReadMore>[Astro의 타입 검사](/ko/guides/typescript/#타입-검사)에 대해 자세히 알아보세요.</ReadMore>

## `astro sync`

<p><Since v="2.0.0" /></p>

:::tip
`astro dev`, `astro build`, `astro check`를 실행하면 `sync` 명령도 실행됩니다.
:::

모든 Astro 모듈에 대한 TypeScript 타입을 생성합니다. 이는 타입 추론을 위한 [`.astro/types.d.ts` 파일](/ko/guides/typescript/#설정)을 설정하고 생성된 타입에 의존하는 기능에 대한 모듈을 정의합니다.

- `astro:content` [콘텐츠 컬렉션 API](/ko/guides/content-collections/)를 위한 모듈
- `astro:db` [Astro DB](/ko/guides/astro-db/)를 위한 모듈
- [실험적 Astro Env](/ko/guides/environment-variables/)를 위한 `astro:env` 모듈
- [Astro Actions](/ko/guides/actions/)를 위한 `astro:actions` 모듈

## `astro add`

구성에 통합을 추가합니다. [통합 안내서](/ko/guides/integrations-guide/#자동-통합-설정)에서 자세히 알아보세요.

## `astro docs`

터미널에서 직접 Astro 문서 웹사이트를 시작합니다.

## `astro info`

현재 Astro 환경에 대한 유용한 정보를 보고합니다. 이슈를 열 때 정보를 제공하는 데 유용합니다.

```shell
astro info
```

Example output:

```
Astro                    v5.14.1
Vite                     v6.3.6
Node                     v22.17.1
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             @astrojs/starlight (v0.35.3)
```

<h3>플래그</h3>

명령의 동작을 사용자 정의하려면 다음 플래그를 사용하세요.

#### `--copy`

이 명령은 프롬프트 없이 출력을 클립보드에 복사합니다.

## `astro preferences`

`astro preferences` 명령으로 사용자 기본 설정을 관리하세요. 프로젝트에 참여하는 모든 사람의 동작을 변경하는 `astro.config.mjs` 파일과 달리 사용자 기본 설정은 개별 Astro 사용자에게만 적용됩니다.

사용자 기본 설정은 기본적으로 현재 프로젝트로 범위가 지정되며 로컬 `.astro/settings.json` 파일에 저장됩니다.

`--global` 플래그를 사용하면 현재 시스템의 모든 Astro 프로젝트에 사용자 기본 설정을 적용할 수도 있습니다. 전역 사용자 기본 설정은 운영 체제별 위치에 저장됩니다.

<h3>사용 가능한 기본 설정</h3>

- `devToolbar` — 브라우저에서 개발 툴바를 활성화하거나 비활성화합니다. (기본값: `true`)
- `checkUpdates` — Astro CLI에 대한 자동 업데이트 확인을 활성화 또는 비활성화합니다. (기본값: `true`)

`list` 명령은 구성 가능한 모든 사용자 기본 설정의 현재 설정을 출력합니다. 또한 기계가 읽을 수 있는 `--json` 출력도 지원합니다.

```shell
astro preferences list
```

터미널 출력 예시:

| 기본 설정               | 값 |
| ------------------------ | ----- |
| devToolbar.enabled       | true  <tr></tr>|
| checkUpdates.enabled     | true  |

기본값을 `enable`, `disable`, 또는 `reset`으로 설정할 수 있습니다.

예를 들어, 특정 Astro 프로젝트에서 devToolbar를 비활성화하려면:

```shell
astro preferences disable devToolbar
```

현재 머신의 모든 Astro 프로젝트에서 devToolbar를 비활성화하려면:

```shell
astro preferences disable --global devToolbar
```

devToolbar는 나중에 다음을 사용하여 활성화할 수 있습니다.

```shell
astro preferences enable devToolbar
```

`reset` 명령은 기본 설정을 기본값으로 재설정합니다.

```shell
astro preferences reset devToolbar
```

## `astro telemetry`

현재 CLI 사용자에 대한 원격 측정 구성을 설정합니다. 원격 측정은 Astro 팀에 Astro 기능이 가장 자주 사용되는 통찰력을 제공하는 익명 데이터입니다. 자세한 내용은 [Astro의 원격 측정 페이지](https://astro.build/telemetry/)를 참조하세요.

다음 CLI 명령을 사용하여 원격 측정을 비활성화할 수 있습니다.

```shell
astro telemetry disable
```

나중에 다음을 사용하여 원격 측정을 다시 활성화할 수 있습니다.

```shell
astro telemetry enable
```

`reset` 명령은 원격 측정 데이터를 초기화합니다.

```shell
astro telemetry reset
```

:::tip[CI 환경에서 원격 측정을 비활성화하고 싶으십니까?]
CI 스크립트에 `astro telemetry disable` 명령을 추가하거나 `ASTRO_TELEMETRY_DISABLED` 환경 변수를 설정하세요.
:::

## `astro create-key`

서버 아일랜드로 전달되는 props를 암호화하기 위한 키를 생성합니다.

```shell
astro create-key
```

이 키를 `ASTRO_KEY` 환경 변수(예: `.env` 파일)로 설정하고, 롤링 배포, 다중 지역 호스팅 또는 서버 아일랜드가 포함된 페이지를 캐싱하는 CDN과 같은 상황에서 [서버 아일랜드를 위한 상수 암호화 키](/ko/guides/server-islands/#암호화-키-재사용)가 필요할 때 CI/CD 또는 호스트의 빌드 설정에 포함하세요.

## 공통 플래그

### `--root <path>`

프로젝트 루트의 경로를 지정합니다. 지정하지 않으면 현재 작업 디렉터리가 루트로 간주됩니다.

루트는 Astro 구성 파일을 찾는 데 사용됩니다.

```shell
astro --root myRootFolder/myProjectFolder dev
```

### `--config <path>`

프로젝트 루트를 기준으로 구성 파일의 경로를 지정합니다. 기본값은 `astro.config.mjs`입니다. 구성 파일에 다른 이름을 사용하거나 구성 파일이 다른 폴더에 있는 경우 이 방법을 사용하세요.

```shell
astro --config config/astro.config.mjs dev
```

### `--force <string>`

<p><Since v="5.0.0" /></p>

[콘텐츠 레이어 캐시](/ko/guides/content-collections/#컬렉션-loader-정의)를 지우고 전체 리빌드를 강제 실행합니다.

### `--mode <string>`

<p><Since v="5.0.0" /></p>

프로젝트의 인라인 [`mode`](/ko/reference/programmatic-reference/#mode) 구성을 설정합니다.

### `--outDir <path>`

<p><Since v="3.3.0" /></p>

프로젝트에 대한 [`outDir`](/ko/reference/configuration-reference/#outdir)를 구성합니다. 이 플래그를 전달하면 `astro.config.mjs` 파일에 `outDir` 값이 있는 경우 이를 재정의합니다.

### `--site <url>`

프로젝트에 대한 [`site`](/ko/reference/configuration-reference/#site)를 구성합니다. 이 플래그를 전달하면 `astro.config.mjs` 파일에 `site` 값이 있는 경우 이를 재정의합니다.

### `--base <pathname>`

<p><Since v="1.4.1" /></p>

프로젝트에 대한 [`base`](/ko/reference/configuration-reference/#base)를 구성합니다. 이 플래그를 전달하면 `astro.config.mjs` 파일에 `base` 값이 있는 경우 이를 재정의합니다.

### `--port <number>`

개발 서버와 미리보기 서버를 실행할 포트를 지정합니다. 기본값은 `4321`입니다.

### `--host [선택적 호스트 주소]`

개발 서버와 미리 보기 서버가 수신 대기해야 하는 네트워크 IP 주소 (예: localhost가 아닌 IP)를 설정합니다. 이는 개발 중 휴대폰과 같은 로컬 장치에서 프로젝트를 테스트하는 데 유용할 수 있습니다.

- `--host` — LAN 및 공용 주소를 포함한 모든 주소에서 수신
- `--host <사용자 정의 주소>` — `<사용자 정의 주소>`에 네트워크 IP 주소 노출

:::caution
프로덕션 환경에서 개발 서버 및 미리보기 서버를 노출하기 위해 `--host` 플래그를 사용하지 마세요. 서버는 사이트를 개발하는 동안에만 로컬 사용을 위해 설계되었습니다.
:::

### `--allowed-hosts`

<p><Since v="5.4.0" /></p>

`dev` 또는 `preview` 모드에서 Astro가 응답할 수 있는 호스트 이름을 지정합니다. 쉼표로 구분된 호스트 이름 목록이나 모든 호스트 이름을 허용하는 `true`를 전달할 수 있습니다.

호스트 이름 허용의 보안 관련 사항을 포함한 자세한 내용은 [Vite의 `allowedHosts` 기능](https://ko.vite.dev/config/server-options.html#server-allowedhosts)을 참조하세요.

### `--verbose`

문제를 디버깅할 때 유용한 자세한 로깅을 활성화합니다.

### `--silent`

콘솔 출력 없이 서버를 실행하는 자동 로깅을 활성화합니다.

### `--open`

서버 시작 시 브라우저에서 앱을 자동으로 엽니다. 열려는 URL을 지정하기 위해 전체 URL 문자열 (예: `--open http://example.com`) 또는 경로 이름 (예: `--open /about`)을 전달할 수 있습니다.

## 전역 플래그

이 플래그를 사용하여 `astro` CLI에 대한 정보를 얻으세요.

### `--version`

Astro 버전 번호를 출력하고 종료합니다.

### `--help`

도움말 메시지를 출력하고 종료합니다.
